Subject: Specify Local Address

From: "John E. Fetvedt (919-254-4366)" <[email-masked]>
Date: Wed, 19 Oct 94 09:51:51 EDT

CIW General,

     As promised at the 10/94 CIW meeting, I have attached the history
of the requirements for the Specify Local Address function.  Sorry about
the long message.

     The previously identified requirements include:

          1. Allow a program to specify the local LU through which it
             will receive support.

             a) To specify which LU to allocate a conversation on.
             b) To specify which LU to accept a conversation on.

          2. Allow a program to specify the local CRM to be used for an
             outgoing conversation.

     I would appreciate your input on the following questions at your
earliest opportunity.

          1. Are you aware of any additional requirements not covered
             above?

          2. If the subject functionality is proposed for CPI-C should
             it be SNA LU 6.2 specific, or should it also apply to OSI
             TP?

          3. Considering the local nature of the function, and its
             potential impact on application portability, do you think
             it is a good candidate for inclusion in CPI-C?

     Thanks in advance for your prompt response.

     Cheers.

John Fetvedt

----------------------------- Referenced Note ---------------------------

=========================================================================

12/93 CIW

===== New Business: Specify Local Address

The CIW accepted a new work item to address requirements for a program
to specify the local LU through which it will receive support.  A
new SIG (Specify Local Address) has been created to work on the item.
Wall Data will be developing a proposal for consideration in March 94.
Those interested in joining the electronic distribution list and who
did not sign up at the CIW meeting, send a request to
[email-masked]
with your e-mail address.

  Approved Direction status for

    - Specify local address

=========================================================================
----- CIWSLADD DIGEST appended at 14:31:30 on 93/12/10 GMT (by NSAECHO at RALVM6)
From: steven hecker <[email-masked]>
Date: Fri, 10 Dec 93 09:14:37 -0500
Message-Id: <[email-masked]>

Although I have not been to the last 2 meetings (we sent someone else),
I am still alive and active in CPI-C. No, the LIRR gunman didn't get me.

I'm not sure what was proposed at the December meeting, but here
are my thoughts:

The way I see it, there are two different reasons for specifying
a local address (LU):
        1) To specify which LU to allocate a conversation on.
        2) To specify which LU to accept a conversation on.

To solve (1) I propose two functions, basically mirroring the
Set_Partner_LU_Name and Extract_Partner_LU_Name functions:

        Set_Source_LU_Name
                cmssln( conversation_ID,
                                source_LU_name,
                                source_LU_name_length,
                                return_code )

        Extract_Source_LU_Name
                cmesln( conversation_ID,
                                source_LU_name,
                                source_LU_name_length,
                                return_code )

        Also, the source_lu should be another parameter to be stored
        in the side information.

To solve (2), I would look for a functiona similar to Specify_TP_Name:

        Specify_Accept_LU_Name

                cmsaln( accept_LU_name,
                                accept_LU_name_length,
                                return_code )

        Do we want the functionality to have a list of local lus to accept
        on (as we do with Specify_TP_Name), or is one LU sufficient? As far
        as I'm concerned, one LU is enough, and the user can change the
        LU for each Accept call, if so desired.

I'm looking forward to hearing other people suggestions.

------------------------
Steve Hecker
Systems Strategies, Inc.
steven@ssiny

=========================================================================
----- CIWSLADD DIGEST appended at 14:45:17 on 93/12/13 GMT (by NSAECHO at RALVM6)
Subject: SNI proposal
From: [email-masked]
Date: Mon, 13 Dec 93 15:00:21  +0100
Message-Id: <[email-masked]>
Apparently-To: [email-masked]
Apparently-To: <NSAECHO@ralvm6>
Apparently-To: <[email-masked]>
Apparently-To: <[email-masked]>
Apparently-To: <[email-masked]>

Responding to Stevens proposal I want to propose a similiar but different
solution.

I dont like the term 'source LU name'. I think we should call it
'local LU name' because it is the LU name in the local system.
At an incoming conversation the source LU is the partner LU.

My proposal for the Set and Extract calls is nearly the same as that
of Steven.

My proposal for the Specify call is a little different. I would like
to allow a program to accept all incoming conversations at a specified
LU indepent of the LU name.

I dont know exactly what was the intention of Dennis Chimienti for
his Specify_Local_LU_Name call. Dennis please send your proposal also
to the ciw-sig-specify-local-address.

Here is my proposal:

Extract_Local_LU_Name (CMELLU)
==============================

    A program uses the Extract_Local_LU_Name call to extract the local_lu_name
    characteristic's value for a given conversation. The value is returned in
    the local_lu_name parameter. It is the name of the local LU to which the
    conversation is attached.

Format
------

    CM_RETCODE  CMELLU( conversation_ID,
                        local_lu_name,
                        local_lu_name_length,
                        return_code )

    char *conversation_ID;
    char *local_lu_name;
    int  *local_lu_name_length;
    int  *return_code;

Parameters
----------

    conversation_ID (input)
        Specifies the conversation identifier.

    local_lu_name (output)
        Specifies the variable containing the name of the local LU to which
        the conversation is attached.

    local_lu_name_length (output)
        Specifies the variable containing the length of the returned
        local_lu_name parameter not including the trailing '\0'.

    return_code (output)
        Specifies the result of the call execution. The return_code variable
        can have one of the following values:

        - CM_OK
        - CM_PROGRAM_PARAMETER_CHECK
            This value indicates that the conversation_ID specifies an
            unassigned conversation identifier.
        - CM_PROGRAM_STATE_CHECK
            This value indicates that the conversation_ID specifies a
            conversation in Reset state.
        - CM_PRODUCT_SPECIFIC_ERROR

Set_Local_LU_Name (CMSLLU)
==========================

    Set_Local_LU_Name is used by a program to set the local_lu_name and
    local_lu_name_length characteristic for a conversation. By executing this
    call the local LU, which is to be used for a new conversation, is
    determined by the program instead of being selected by Node Services.

    A program cannot issue the Set_Local_LU_Name call after an Allocate is
    issued. Only the program that initiates the conversation (using the
    Initialize_Conversation call) can issue this call.

    The partner program, after having accepted the conversation using the
    Accept_Conversation call, can extract the name of the initiating LU
    by means of the Extract_Partner_LU_Name call.

Format
------

    CM_RETCODE  CMSLLU( conversation_ID,
                        local_lu_name,
                        local_lu_name_length,
                        return_code )

    char *conversation_ID;
    char *local_lu_name;
    int  *local_lu_name_length;
    int  *return_code;

Parameters
----------

    conversation_ID (input)
        Specifies the conversation identifier.

    local_lu_name (input)
        Specifies the name of the local LU that shall be used for the new
        conversation.

    local_lu_name_length (input)
        Specifies the length of the local LU name not including the trailing
        '\0'. The length can be from 1 to 17 bytes.

    return_code (output)
        Specifies the result of the call execution. The return_code variable
        can have one of the following values:

        - CM_OK
        - CM_PROGRAM_STATE_CHECK
            This value indicates that the conversation is not in Initalize
            state.
        - CM_PROGRAM_PARAMETER_CHECK
            This value indicates one of the following:
            - The conversation_ID specifies an unassigned conversation
              identifier.
            - The local_lu_name_length specifies a value less than 1 or greater
              than 17.
            - The name specified in local_lu_name does not specify a local LU
              known by Node Services.
        - CM_PRODUCT_SPECIFIC_ERROR

Specify_Local_LU_Name (CMSLLN)
==============================

    Specify_Local_LU_Name is used by a program to inform Node Services that
    all incoming conversation startup requests received over the specified
    local LU shall be delivered to that program, irrespective of the TP name
    specified in the request.

Format
------

    CM_RETCODE  CMSLLN( local_lu_name,
                        local_lu_name_length,
                        return_code )

    char *local_lu_name;
    int  *local_lu_name_length;
    int  *return_code;

Parameters
----------

    local_lu_name (input)
        Specifies the name of the local LU.

    local_lu_name_length (input)
        Specifies the length of the local LU name not including the trailing
        '\0'. The length can be from 1 to 17 bytes.

    return_code (output)
        Specifies the result of the call execution. The return_code variable
        can have one of the following values:

        - CM_OK
        - CM_PROGRAM_PARAMETER_CHECK
            This value indicates one of the following:
            - The local_lu_name_length specifies a value less than 1 or greater
              than 17.
            - The name specified in local_lu_name does not specify a local LU
              known by Node Services.
        - CM_PRODUCT_SPECIFIC_ERROR

Usage Notes
-----------

1)  The following collision may occur:

    - Program A calls Specify_Local_LU_Name for the local LU LU_X to tell
      Node Services that it will accept all conversations initiated on LU_X.

    - Program B calls Specify_Local_TP_Name with TP_name = TP_B to register
      itself with Node Services and associate the name TP_B with itself.

    If in this situation Node Services receives a conversation startup request
    over LU_X specifying the destination TP name TP_B, a collision exists
    which Node Services will resolve in favour of program A, that is,
    the conversation startup request will be delivered to the program that
    issued the Specify_Local_LU_Name call.

My proposal assumes that a program cannot use both Specify_Local_TP_Name
and Specify_Local_LU_Name. But there are still possibilities to do this.

For example, if a program is willing to accept conversations only with a
given TP name and a given LU name, it could use both calls.

Which calls should be made, if a program is willing to accept conversations
with TP name TPA on LU LUX and TP name TPB on LU LUY?
Which calls should be made, if a program is willing to accept conversations
with TP name TPC on each LU and TP name TPB only on LU LUZ?

I think here is some work to do for the SIG.

Regards
Peter

-----------------------------------------------------------------------------
Peter Binninger                         Tel.:  07531-87-4758
Computer Gesellschaft Konstanz mbH      Fax:   07531-87-4888
(Siemens Nixdorf Informationssysteme)   Email: [email-masked]
Max-Stromeyer-Strasse 116
78467 Konstanz
Germany

=========================================================================
----- CIWGEN DIGEST appended at 15:40:59 on 94/01/03 GMT (by NSAECHO at RALVM6)
Subject: Resending note form Dennis Chimienti
From: "Jack Sanders (8-444-4459)" <[email-masked]>
Date: Mon, 3 Jan 94 09:53:26 EST
Message-Id: <[email-masked]>

From: Chimienti, Dennis
To: 'CIW'
Subject: Specify Local LU Name
Date: Tuesday, December 14, 1993 5:08PM

I hope that the following pages clearify my intention at the December CIW
meeting concerning  the new CPI-C calls: Specify_Local_LU _Name  and
Extract_Local_LU_name.

Dennis Chimienti         Phone     (206) 788-0250
Wall Data      Fax  (206) 788-0137

Background
        Historically CPI-C has failed to address the issue of how the Local LU
    name is made visible to the underlying API. As a result several non CPI-C
    solutions have been devised by implementors to address this issue. These
    solutions have been cumbersum for third party venders and end users to
    deal with. This proposal suggests that we allow CPI-C to have control over
    the Local LU.

Overview:
        The CPI-C call "Specify_Local_LU_Name" will allow a Transaction
    Program to change the Local LU name that it wishes to use on a per
    conversation basis. Furthermore a TP will be able to have multiple
    conversations with one or more Hosts and use a different Local LU name
    for each conversation. An end user who wishes to change or view the Local
    LU name will not have to use a special configuration utility or access
    environment variables.
        For a TP that plans to initiate a Conversation it would specify an
    LU name after it has done a cminit and before it has done a cmallc. In
    other words the CPI-C API must be in state 1 (Initialize).
        For a TP that plans to accept a Conversation it would specify an LU
    name after it has done a cminic and before it has done a cmacci. In other
    words the CPI-C API must be in state 14 (Initialize for Incoming).
    In both of the above cases the conversation Id is used to tie a Local
    LU name to a set of allocated resources. This is useful for implementers
    of the CPI-C API and of the Transaction Programs. Especially when it
    comes to deallocating any resources associated with a particular Local LU.
    The Local Lu name specified belongs to the Conversation who issued the
    Specify_Local_LU_Name call (CMSLLN) and is only valid for the duration of
    that Conversation.
    The Local LU name should also be added to the Side Information Table which
    contains other "Critical" conversation parameters. This will allow a user
    to have a "Default" Local LU name available.

Specify_Local_LU_name (CMSLLN)
    A program uses the Specify_Local_LU_name (CMSLLN) call to define the name
    of the Local LU it wishes to use for the current conversation. This new
    Local LU name is only valid for the duration of this conversation.
    A program can extract the Local LU name with the Extract_Local_LU_name
    call.

    Note 1: For the initiating side this call will only be allowed after a
            cminit is issued, and before a cmallc is issued.
    NOte 2: For the accepting side this call will only be allowed after a
            cminic is issued, and before a cmacci is issued.

Format:
    CALL CMSLLN( conversation_ID,
                 LU_name,
                 LU_name_length,
                 return_code )

Parameters:
    Conversation_ID(input)
        Specifies the conversation identifier.

    LU_name (input)
        Specifies the name by which the local LU wants to be identified for
        the duration of this conversation.

    LU_name_length (input)
        Specifies the length of the local name. The length can be from 1 to 8
        bytes.

    return_code
    - CM_OK
    - CM_PROGRAM_STATE_CHECK
    - CM_PROGRAM_PARAMETER_CHECK
    - CM_OPERATION_NOT_ACCEPTED
    - CM_PRODUCT_SPECIFIC_ERROR
        + LU name length is not within the proper range of 1 to 8 bytes.

State Changes:
    This call does not cause any state changes.

Usage Notes

    1. The Local LU name uses the local system's native encoding.
    2. If a return code other than CM_OK is returned on the call, then
       the Local LU name is unchanged.

Extract_Local_LU_name (CMELLN)
    A program uses the Extract_Local_LU_name (CMELLN) call to examine the name
    of the the Local LU.

    Note 1: If a valid non-zero Conversation Id is supplied, then the Local LU
            name belonging to that conversation is returned. This form of the
            call has no meaning in state 0 (Reset State).
    Note 2: If the Conversation Id is NULL, then the Default Local LU name
            from the Side Information Table is returned. This form of the call
            is allowed in any state.

Format:
    CALL CMELLN( conversation_ID,
                 LU_name,
                 LU_name_length,
                 return_code )

Parameters:
    Conversation_ID(input)
        Specifies the conversation identifier.

    LU_name (input)
        Specifies the name by which the local LU is identified for the current
        conversation.

    LU_name_length (input)
        Specifies the length of the local name. The length can be from 1 to 8
        bytes.

    return_code
    - CM_OK
    - CM_PROGRAM_STATE_CHECK
    - CM_PROGRAM_PARAMETER_CHECK
    - CM_OPERATION_NOT_ACCEPTED
    - CM_PRODUCT_SPECIFIC_ERROR
        + Invalid conversation ID
        + LU name length is not within the proper range of 1 to 8 bytes.

State Changes:
    This call does not cause any state changes.

Usage Notes

    1. The Local LU name uses the local system's native encoding.

=========================================================================
----- CIWGEN DIGEST appended at 22:35:56 on 94/01/28 GMT (by NSAECHO at RALVM6)
Subject: Comments on Specify Local LU Name proposal
From: "Plank, Larry K (1-507-253-4750)" <[email-masked]>
Date: Fri, 28 Jan 94 15:22:42 CST
Message-Id: <[email-masked]>
X-Addr: 43Q/015-2
        SNA Connectivity Dev
        Rochester, Mn
        Internet:  [email-masked]

Just a couple of observations on the proposal by Dennis Chimienti to add
Set/Extract_Local_LU_Name calls to CPIC.

The LU_name_length would have to be 1 to 17 characters on both calls in order
to provide Fully Qualified LU Names.

I don't understand the reason you are requesting this call. The CPIC API was
created to be a simple easy to use interface that one could use to write
portable applications. To reach this end the partner LU, local LU, mode, and
TPN were moved to the side information. It was deemed necessary in order to
make a portable pgm and shield the appl developer from all this "comm" stuff.
So it was moved to the side info where a system pgm could handle it. If we add
a CMSLLN call, now the pgm gets involved and the program does not port. It not
only won't port from one platform to another eg. Apple to AS/400 but it would
not port from one AS/400 box to another without change to the appl or change to
the network to move the specified LU along with the appl from one box to
another to avoid duplicate LU names in the same network.

I question the necessity and wisdom of providing this call. It is also not
clear in your proposal what happens if the specified LU is not defined on the
node. Would you be expecting a local LU to be defined, if yes then we need a
lot more information. I would oppose doing this. I would assume the call would
fail.
Larry Plank

=========================================================================
 3/94 CIW

  The Specify Local Address work item opened at the December93 meeting
  was resolved for lack of requirement.

=========================================================================
 6/94 CIW

Specify Local TPN/Accept Specific
    Jack Sanders lead a discussion on specify local TP Name
    and Accept Specific requirements. Consensus was reached
    to open a work item for the following two requirements:

    1. Enhanced server support - allow a multi-threaded server
    to create threads, each of which can accept incoming
    conversations for a different TP name.  That is, allow a
    program to accept a conversation for a specific TP name.

    2. Allow a program to specify the local CRM to be
    used for an outgoing conversation.

    In addition, consensus was reached on the following
    solution direction for requirement number 1.

    Extend Set_TP_Name
        - allow in Initialize_Incoming state
        - subsequent Accept_Incoming accepts an incoming
          conversation only for the specified TP name

    This work item will be carried in the technical plan as
    Specify Local TPN/Accept Specific.

=========================================================================